---
title: AppManagerBase
summary: API reference for AppManagerBase.
status: draft
owner: SAIF BOF documentation team
last_reviewed: 2026-08-21
library: SAIF.Application
reference_type: embedded
---

# AppManagerBase

`AppManagerBase` is the abstract base every concrete Application-tier manager in the SAIF BOF stack must inherit from. It owns the security-role gating state (`AppSecurityRole`), context-set tracking, message accumulation, and the lazily-created `ApplicationDataAccess` data layer, while requiring subclasses to supply their own initialize/retrieve/write/transaction/security/context-validity behavior through a fixed set of `MustOverride` hooks. It also inherits `clsBusinessBase`†, making every concrete subclass simultaneously a BOF business object (with an inherited rule-engine/edit-session/save lifecycle) and an application-process controller with its own parallel lifecycle.

## Purpose
- Define and enforce the abstract application-manager lifecycle contract (`Initialize` → `OnInitialize` → `OnCreateDataLayer`; `OnCheckSecurity`; `OnTransactionStart`/`OnWrite`/`OnTransactionStop`; `OnRetrieve`) that every concrete subclass must implement ([BR-APP-004](../../business-rules.md#br-app-004-retrieve-none-write-none-abstract-contract)).
- Hold whole-object access-level state (`AppSecurityRole`) and expose read-only gates (`IsAccessible`, `IsUpdateable`, `IsViewOnly`, `IsRestricted`) derived from it, defaulting to `NoAccess` (fail-closed) until a subclass marks the role ([BR-APP-002](../../business-rules.md#br-app-002-application-access-level-gating)).
- Accumulate non-duplicate, non-empty display messages into a single `Message` string ([BR-APP-001](../../business-rules.md#br-app-001-non-empty%2C-non-duplicate-message-accumulation)).
- Lazily create and hold an `ApplicationDataAccess` instance for named data-portal registration, and allow direct portal injection via `InjectDPI`.

## Context
- Namespace: `SAIF.Application`
- Assembly/package: `SAIF.Application` (embedded library)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `SecurityPrincipal` | `Protected ReadOnly Property SecurityPrincipal As clsSecurityPrincipal` | Holds the security principal supplied at construction; used by subclass `OnCheckSecurity()` implementations to determine access. |
| `DataLayer` | `Protected ReadOnly Property DataLayer As ApplicationDataAccess` | Lazily creates and returns the data-portal registry a subclass populates in `OnCreateDataLayer()`. |
| `ContextSet` | `Public ReadOnly Property ContextSet As Boolean` | Reports whether the manager's operating context has been marked set via `MarkContextSet`. |
| `IsAccessible` | `Public ReadOnly Property IsAccessible As Boolean` | Gates whether any access (view or update) is permitted, derived from `SecurityRole`. |
| `IsRestricted` | `Public ReadOnly Property IsRestricted As Boolean` | Reports whether the current `SecurityRole` denies all access (`NoAccess`). |
| `IsUpdateable` | `Public ReadOnly Property IsUpdateable As Boolean` | Reports whether the current `SecurityRole` permits update operations. |
| `IsViewOnly` | `Public ReadOnly Property IsViewOnly As Boolean` | Reports whether the current `SecurityRole` restricts the caller to view-only access. |
| `Message` | `Public ReadOnly Property Message As String` | Exposes the accumulated, de-duplicated display message string built by `AppendMessageLines`. |
| `NewLineCharacter` | `Public Property NewLineCharacter As String` | Configurable line separator used when appending message lines. |
| `SecurityRole` | `Public ReadOnly Property SecurityRole As AppSecurityRole` | Exposes the current access-level role set by `Mark*` methods ([BR-APP-002](../../business-rules.md#br-app-002-application-access-level-gating)). |
| `ValidContext` | `Public ReadOnly Property ValidContext As Boolean` | Exposes whether the current context has been validated via the subclass-implemented `OnValidContext()` hook. |
| `AppendMessageLines` (3 overloads) | `Public Sub AppendMessageLines(inMessage As String)` / `(inMessages As String())` / `(inMessages As IEnumerable(Of String))` | Appends one or more messages to `Message`, skipping empty or already-present entries ([BR-APP-001](../../business-rules.md#br-app-001-non-empty%2C-non-duplicate-message-accumulation)). |
| `MarkContextNotSet` | `Public Sub MarkContextNotSet()` | Clears the `ContextSet` flag. |
| `MarkContextSet` | `Public Sub MarkContextSet()` | Sets the `ContextSet` flag, indicating the manager's operating context is established. |
| `MarkUpdate` | `Public Sub MarkUpdate()` | Sets `SecurityRole` to `Update`, permitting update access ([BR-APP-002](../../business-rules.md#br-app-002-application-access-level-gating)). |
| `MarkNoAccess` | `Public Sub MarkNoAccess()` | Sets `SecurityRole` to `NoAccess`, the fail-closed default ([BR-APP-002](../../business-rules.md#br-app-002-application-access-level-gating)). |
| `MarkViewOnly` | `Public Sub MarkViewOnly()` | Sets `SecurityRole` to `ViewOnly`, restricting the caller to read access ([BR-APP-002](../../business-rules.md#br-app-002-application-access-level-gating)). |
| `Initialize` | `Public Sub Initialize()` | Invokes `OnInitialize()` then `OnCreateDataLayer()` to bring a concrete subclass instance to a usable state. |
| `New` | `Protected Sub New(inSecurityPrincipal As clsSecurityPrincipal)` | Stores the supplied security principal for later use by `OnCheckSecurity()`. |
| `InjectDPI` | `Public Sub InjectDPI(inKey As String, inDPI As IDataPortalInfo)` | Allows a subclass to inject a pre-built data portal directly into the data layer, bypassing `CreateSQLServerPortal`/`CreateOraclePortal`. |
| `OnInitialize` | `Protected MustOverride Sub OnInitialize()` | Abstract hook a subclass implements for its own initialization logic. |
| `OnCreateDataLayer` | `Protected MustOverride Sub OnCreateDataLayer()` | Abstract hook a subclass implements to populate `DataLayer` with named data portals. |
| `OnContextChanged` | `Protected MustOverride Sub OnContextChanged()` | Abstract hook invoked when the manager's operating context changes. |
| `OnCheckSecurity` | `Protected MustOverride Sub OnCheckSecurity()` | Abstract hook a subclass implements to determine and set `SecurityRole` via `Mark*` methods ([BR-APP-002](../../business-rules.md#br-app-002-application-access-level-gating)). |
| `OnTransactionStart` | `Protected MustOverride Sub OnTransactionStart()` | Abstract hook invoked at the start of a write transaction. |
| `OnTransactionStop` | `Protected MustOverride Sub OnTransactionStop()` | Abstract hook invoked at the end of a write transaction. |
| `OnRetrieve` | `Protected MustOverride Sub OnRetrieve()` | Abstract hook a subclass implements to perform its retrieve logic. |
| `OnWrite` | `Protected MustOverride Sub OnWrite()` | Abstract hook a subclass implements to perform its write logic. |
| `OnValidContext` | `Protected MustOverride Function OnValidContext() As Boolean` | Abstract hook a subclass implements to validate the current context, backing `ValidContext`. |
| `Retrieve` | `Public MustOverride Sub Retrieve()` | Abstract member every subclass must implement for its retrieve operation ([BR-APP-004](../../business-rules.md#br-app-004-retrieve-none-write-none-abstract-contract)). |
| `Write` | `Public MustOverride Sub Write()` | Abstract member every subclass must implement for its write operation ([BR-APP-004](../../business-rules.md#br-app-004-retrieve-none-write-none-abstract-contract)). |

## Inherited public members

Members in this section are inherited from `clsBusinessBase` in `SAIF.Framework.Core`. They are available on this type through inheritance.

| Member | Signature | Purpose | Origin |
| --- | --- | --- | --- |
| `Rules` | `Public ReadOnly Property Rules As clsRulesManager` | Holds the rule-engine instance that evaluates business rules in severity order and tracks broken rules.† | `SAIF.Framework.Core` — `clsBusinessBase` |
| `BeginEdit` | `Public Sub BeginEdit()` | Opens an edit session on the object.† | `SAIF.Framework.Core` — `clsBusinessBase` |
| `CancelEdit` | `Public Sub CancelEdit()` | Rolls back an open edit session.† | `SAIF.Framework.Core` — `clsBusinessBase` |
| `ApplyEdit` | `Public Sub ApplyEdit()` | Commits an open edit session.† | `SAIF.Framework.Core` — `clsBusinessBase` |
| `SetPreviousLink` / `SetNextLink` / `InsertLinkAfter` / `InsertLinkBefore` / `RemoveLinks` | Link-management methods | Manage sibling/linked-object relationships for the business object.† | `SAIF.Framework.Core` — `clsBusinessBase` |
| `Error` / `Item(columnName)` | `IDataErrorInfo` support | Surfaces broken-rule validation errors for data-binding scenarios.† | `SAIF.Framework.Core` — `clsBusinessBase` |
| `DumpState` | `Public Function DumpState() As String` | Serializes the object's current state for diagnostics.† | `SAIF.Framework.Core` — (base of `clsBusinessBase`) |
| `AllowCache` | `Public Property AllowCache As Boolean` | Controls whether the object's data-portal results may be cached.† | `SAIF.Framework.Core` — (base of `clsBusinessBase`) |

## Behavioral notes
- No direct evidence in `AppManagerBase.vb` shows the inherited `clsBusinessBase` rule/edit/save machinery being invoked by this library's own code — the two lifecycles (inherited business-object lifecycle vs. this class's own `On*` lifecycle) coexist but are used independently here.*
- Two distinct, identically-named `AppSecurityRole` enum declarations exist — one nested in this class and one top-level in `Enums.vb`; which one downstream consumers reference could not be determined from this library alone.**

## Constraints and usage notes
- Every concrete subclass must implement all `MustOverride` members; the VB.NET compiler prevents instantiation otherwise ([BR-APP-004](../../business-rules.md#br-app-004-retrieve-none-write-none-abstract-contract)).
- Until a subclass's `OnCheckSecurity()` implementation calls a `Mark*` method, the instance defaults to `NoAccess` (`IsRestricted = True`, `IsAccessible = False`).

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified. Statements marked with
> † were retrieved from dependency library documentation via the Legends CLI RAG service. They
> describe inherited behavior from the indicated origin library and should be verified if the
> dependency version changes.

## Sources
- `SAIF.Application\AppManagerBase.vb`